fix(plugin-auth)!: clearing the allowed IP ranges applies at once, and a console save that leaves out the saving address is refused - #30309

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-auth, @objectstack/service-settings, touching 31 documentable anchor(s).

14 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via SettingsService (symbol, a top-level class))
• content/docs/deployment/cli.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/deployment/self-hosting.mdx (via AuthPlugin (symbol, a top-level class), COPY (symbol, a top-level const object))
• content/docs/deployment/tenancy-modes.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/kernel/runtime-services/settings-service.mdx (via setMany (symbol, a method of class SettingsService))
• content/docs/kernel/services-checklist.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via AuthPlugin (symbol, a top-level class), allowed_ip_ranges (literal, a string literal in bindAuthSettings))
• content/docs/permissions/authorization.mdx (via allowed_ip_ranges (literal, a string literal in bindAuthSettings))
• content/docs/permissions/record-view-auditing.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/plugins/index.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/protocol/kernel/config-resolution.mdx (via SettingsService (symbol, a top-level class), registerSettingsRoutes (symbol, a top-level function), setMany (symbol, a method of class SettingsService))
• content/docs/protocol/kernel/index.mdx (via SettingsService (symbol, a top-level class))
• content/docs/upgrading.mdx (via AuthPlugin (symbol, a top-level class))

⛔ 8 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v14.mdx (via setMany (symbol, a method of class SettingsService))
• content/docs/releases/v17/17-3.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/releases/v17/17-5.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/releases/v17/17-6.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/releases/v18/18-0.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/releases/v18/18-1.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/releases/v18/18-2.mdx (via AuthPlugin (symbol, a top-level class))
• content/docs/releases/v18/index.mdx (via AuthPlugin (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f13607b3d76935a7595fbeeefa033155b4a4b8b1 && git checkout f13607b3d76935a7595fbeeefa033155b4a4b8b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin c1240a38ac2c23c8d526e476a20edeabbbefd6f6 8767d6aa81725636037589b29b3ad59a9b4a37e9 && git checkout -B drift-repro c1240a38ac2c23c8d526e476a20edeabbbefd6f6 && git merge --no-ff 8767d6aa81725636037589b29b3ad59a9b4a37e9

node scripts/docs-audit/affected-docs.mjs --json c1240a38ac2c23c8d526e476a20edeabbbefd6f6

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs c1240a38ac2c23c8d526e476a20edeabbbefd6f6 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#2 · os-bill · session_01Utp6Cbvcmv8YWFhFJwzjKL

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 89ff3aa9e1d941b2a20ed3c33ebc13c81ea18f55
Local-runs: none
Scope: packages/plugins/plugin-auth/src/allowed-ip-ranges.ts, packages/plugins/plugin-auth/src/allowed-ip-ranges.pin.test.ts, packages/plugins/plugin-auth/src/auth-plugin.ts, packages/services/service-settings/src/index.ts, packages/services/service-settings/src/settings-routes.ts, packages/services/service-settings/src/settings-service.ts, packages/services/service-settings/src/settings-service.types.ts, .changeset/30203-allowed-ip-ranges-live.md + packages/plugins/plugin-auth/src/client-address.ts (the trust rule), packages/plugins/plugin-auth/src/auth-manager.ts (ipMatchesRange, unmapIpv4, isClientIpAllowed, resolveClientAddress, applyConfigPatch), the sign-in gate and the per-piece application in auth-plugin.ts (the registerAuthRoutes D5 block and applyPiece), packages/services/service-settings/src/manifests/auth.manifest.ts (allowed_ip_ranges, scope global), effectiveEnvOverride / coerceEnvValue / registerWritePredicate / setMany pre-flight in settings-service.ts, packages/plugins/plugin-hono-server/src/adapter.ts (readRemoteAddress), packages/spec/src/contracts/http-server.ts (remoteAddress), docs/adr/0069-enterprise-authentication-hardening.md D5, scripts/pm/clause2-line.mjs and scripts/check-changeset-no-major.mjs (for ②), and PR #30298 at 249ec4c4 (for ③). Inputs: card #30203 body and comments 6648444250, 6649086146, 6650755695; PR body, file list, net diff origin/main...89ff3aa9 (8 files, +507 / -12); the head's check-runs.

① Derived judgments

• Which doors are judged — right. The predicate runs inside SettingsService.setMany (refuseByWritePredicates, after the declared constraints, before any row) and judges only when the input carries transport. The only producer of transport is the PUT /api/settings/:namespace route, which always sets it (headers always; remoteAddress when the adapter has one). So: the console save is judged; an in-process set / setMany (boot, seed, migration, an auth:configure host, resetNamespace) carries no request and is let through; a null (clear) returns before any address is read. A boot or non-request write must be neither refused nor skipped: there is no caller connection to lock out, and refusing one would brick a seeded deployment. Correct. A request write that is not the console — an IaC runner or a CLI calling the REST door from a host outside the list — IS refused; that is the rule applied honestly (the gate would refuse that host too), and the refusal names the recovery.
• Clearing semantics — right. declaredAllowedIpRanges is captured at init after ctx.trigger('auth:configure', authConfig) (so a host handler's list counts), and the else if (this.allowedIpRangesFromSettings) branch only emits a patch when the running list came from a stored setting, so a deployment that never stored one sees no extra patch. The reset rides the non-refusable patch piece, applyConfigPatch spreads allowedIpRanges whole, and isClientIpAllowed reads an empty array as open. A cleared value with a deployment-declared list returns to that list, not to none (pinned). isExplicit is untouched, so the sibling keys keep the old behaviour, reported in ③.
• The env pin — right. OS_AUTH_ALLOWED_IP_RANGES='' is a string in this.env, coerceEnvValue hands it back unchanged for a textarea, the key resolves source: 'env', isExplicit is true, parseAllowedIpRanges('') is [], the gate opens (pinned). While pinned the key is locked, so the console save is refused 409 SETTINGS_LOCKED in the pre-flight, before any predicate.
• The new public surface — the declaration is WRONG. @objectstack/service-settings is a published package (private unset, 18.3.0). This head adds two exports to its index.ts (SettingsWriteOptions, SettingsRequestTransport), widens setMany's fourth parameter from SettingsDisplayOptions to SettingsWriteOptions, and adds transport to SettingsWritePredicateInput, the input every predicate author reads. That is a purely additive widening of a published package's public surface — the question the Clause-②: line answers (扩大公开面吗) — and the dispatch itself said yes for new published code. The PR body and the changeset declare no (narrowing) and say "nothing is widened", while the same changeset's fourth bullet describes exactly this widening. The honest line is Clause-②: yes (narrowing): a diff that widens one surface (the settings write seam) and narrows another (the console save). Under ruling A the level is decoupled from this line, so patch stays correct with Metadata-protocol: none; the narrowing arm keeps this review at CONTRACT_REVIEW_TIER. Must-fix (see ②).

② Semver level

• Changeset .changeset/30203-allowed-ip-ranges-live.md: @objectstack/plugin-auth: patch, @objectstack/service-settings: patch. Level right: Metadata-protocol: none takes patch; a non-protocol narrowing ships patch with its BREAKING banner (AGENTS.md Post-Task Checklist step 3, ruling A). The **BREAKING** banner is present and states who moves and how; the ADR-0087 marker is present, disposition not-required, category no-migration-prescription, and the body carries no FROM → TO prescription (the "Who moves" bullet is prose, no arrow and no table), so the category holds. Check Changeset and the lint gate that runs the ADR-0087 registration are green on this head.
• Declaration lines: Clause-②: and Metadata-protocol: are byte-identical between the PR body and the changeset. Both are wrong in the same way (① last bullet). Must-fix: rewrite the line in BOTH places to Clause-②: yes (narrowing) with reasoning that names the widened surface (the two new service-settings exports, the setMany options and the predicate input) and the narrowed one (the console save); keep Metadata-protocol: none and both patch levels. A yes with none and patch is the shape ruling A made legal; nothing else in the changeset needs to move.

③ Boundary flags

• Four service-settings files outside the claimed surface (packages/plugins/plugin-auth/src/ plus a changeset): read and accepted as necessary — the save door had no way to carry the caller's connection to a predicate, the extension is additive and optional, no packages/spec change, no new error code, settings key or env var. Accepted here as a declared deviation; its consequence is the ② correction above, not a reversal.
• Manifest help text unchanged: accepted. The allowed_ip_ranges description already states the trust-proxy rule; the refusal text carries the self-lockout lesson. The docs half (content/docs/permissions/authentication.mdx: refusal and OS_AUTH_ALLOWED_IP_RANGES recovery) and the console half (show the caller's address before saving, read constraint.clientAddress) are named for the seat; both must become cards, not stay as notes.
• Full dogfood red on permission-set-clone-door.dogfood.test.ts: read as main-caused (fix(plugin-security): every member reads and posts comments, and reads the activity history, of the records they can read #30222 grants on sys_comment / sys_activity); nothing in this diff touches permission sets, metadata validation or the clone door. The seat's out-of-scope list names it with dedupe words; it is a class-a defect and must be filed as a card under the main-red convention, not left as a note.
• The clear-skips family (lockout_threshold, max_concurrent_sessions_per_user, every if (isExplicit(key)) branch without a reset): a reproducible defect measured on the real composition; Prime Directive chore: version packages #10 says file it. The report carries it as an out-of-scope finding with dedupe words; the seat files the card. Scope choice (this key only) is accepted: the general fix crosses the refusable pieces Organization require-MFA can be turned on with two-factor off, and after the grace period everyone is locked out with no way to enroll #30201 / Authentication settings: turning off email and password with no other sign-in method saves without warning, and everyone is locked out #30202 are editing.
• Composition with PR fix(plugin-auth)!: saving the auth settings refuses to turn off the last way to sign in #30298 (card Authentication settings: turning off email and password with no other sign-in method saves without warning, and everyone is locked out #30202, same seat), read at its head 249ec4c4: its diff touches auth-plugin.ts only at the top of bindAuthSettings (one import, one registerSignInMethodFloor(settings, …) call) and no service-settings file; this PR's auth-plugin.ts hunks are the SettingsReadSurface member, two fields, the declaredAllowedIpRanges capture, the allowed_ip_ranges branch and the predicate registration before applySettings(). Disjoint lines, both register predicates on different keys through the same last-wins-per-key seam: textual merge clean, semantics compose. Conflict risk, flagged: fix(plugin-auth)!: saving the auth settings refuses to turn off the last way to sign in #30298's body names a batch field on SettingsWritePredicateInput as a possible follow-up. If it is added, the types file grows next to the transport? member this PR adds (same hunk region) and the predicate call in refuseByWritePredicates — which this PR reshapes into a multi-line object literal — is the line both would edit; whichever lands second takes a rebase there. Both fields being optional, the two compose once rebased. No ruling needed.
• Open questions in the os-dev-report: none declared; none found.

④ Design judgment

Judged on the tree, against the sign-in gate and the settings service as cited.

• Same address on both doors — holds. The sign-in gate resolves mgr.resolveClientAddress({ headers, ...transportOf(c) }) and judges isClientIpAllowed; the predicate resolves mgr.resolveClientAddress({ headers, remoteAddress }) from the route's req.headers / req.remoteAddress and judges ipMatchesRange. Both read trustProxy live from the manager's config, both read the same forwarded-header list (client-address.ts, leftmost X-Forwarded-For, then X-Real-IP, believed only under trustProxy), and the hono adapter fills IHttpRequest.remoteAddress from the same socket readRemoteAddress reads. trustProxy off: the proxy's address is judged at both doors (so an admin behind an untrusted proxy saving the office range is refused, naming the proxy address — correct, that is the deployment's bug and the gate would refuse the same). trustProxy on: the forwarded client address at both. Pinned both ways.
• Undetermined address — holds. resolveClientAddress returns undefined when neither fact exists; the gate refuses such a request while any list is set; the predicate refuses any non-empty list with clientAddress: null and the undetermined copy. Consistent; pinned.
• IPv4-mapped / IPv6. unmapIpv4 folds ::ffff:a.b.c.d on both sides, so a dual-stack peer saves and signs in against an IPv4 range (pinned with ::ffff:127.0.0.1). Plain IPv6 matches exact-only on both doors, and an IPv6 CIDR never matches anywhere (ipMatchesRange falls back to exact match when either side is not IPv4) — a pre-existing gate limitation, now consistently applied at the save. Should-fix: the outside copy says the list "does not include" the address; for an admin at 2001:db8::1 saving 2001:db8::/32 the list does include it textually and the matcher cannot read it. Word it as "does not match" or name the matcher's reach (IPv4 CIDR and exact addresses), and file the IPv6-CIDR gap as a card against the gate (the manifest description promises "CIDR ranges" unqualified).
• CIDR parsing errors — no crash path. parseAllowedIpRanges splits and trims only; ipMatchesRange never throws (/33, a non-numeric prefix or a hostname fall to exact match). A malformed-only list is refused at the save because nothing can match the caller — a protective side effect, not validation; a mixed list saves with the malformed entry inert, as before. Pre-existing; no finding against this PR.
• Non-HTTP contexts — allowed, by construction. No transport ⇒ undefined before any read; no authManager yet ⇒ undefined. Nothing crashes. The only in-tree in-process writers of settings outside this package write other keys. Right.
• Env-pinned key and restore-default. Covered in ①: a locked key refuses 409 before predicates; resetNamespace and a null save both resolve default, fire the subscription, and the else-branch returns the gate to the declared list (pinned).
• Forging transport — not reachable. transport is the route's fourth argument to setMany, never read from the body; a body key transport (or values.transport) is an unknown key and the pre-flight refuses the batch 400 UNKNOWN_KEY. A spoofed X-Forwarded-For is believed only under trustProxy, exactly as the gate believes it; the caller already holds manage_platform_settings, so the check is a self-lockout belt, not an authorization control — and it is spelled so in the types. Right.
• Should-fix (information flow): SettingsRequestTransport.headers hands the ENTIRE header map — cookie, authorization, API keys — to every write predicate any plugin registers, while the only consumer reads the forwarded-address family. Narrow what the route forwards to the forwarded-address headers (or document in the TSDoc that a predicate receives credential-bearing headers and must not log or store them). The current TSDoc says the transport "is never stored or logged"; nothing enforces that on a predicate author.
• Should-fix (nit): SettingsReadSurface.registerWritePredicate? takes its input as any; unknown with the structural AllowedIpRangesWriteInput pick keeps plugin-auth free of a service-settings type dependency without an any.
• Tests: the pin boots the real AuthPlugin, the real SettingsService with the shipped auth manifest and the real settings routes through the vitest alias; @objectstack/service-settings is a workspace devDependency of plugin-auth, so the file runs in Test Core. Nine cases cover each branch the four ablations name. Good.
• Degradation levels: the predicate-registration catch logs warn (functional: the belt is missing, the gate still enforces) — right level.

Check-runs on 89ff3aa9 (polled every two minutes from 05:47 to 05:57 UTC, the ten-minute cap): green — Lint & Repo Gates and every Lint · lane, Governed Surface Queue Guard, Check Changeset, Check PR Size, Dogfood Regression Gate, Test Core (2/8, 5/8, 6/8, 7/8, 8/8), Type Check · source gates, Type Check · debt ledger, Type Check · consumer gates, Type Check · workspace, Build Core, Test UI, Live E2E UI, the PR-body guards. Still in_progress at the last poll: Test Core (1/8, 3/8, 4/8). No red on this head; judged with what is there. The verdict below does not depend on them: it is decided by the declaration defect in ②.

Findings

• MUST-FIX (①/②): Clause-②: no (narrowing) is false on the tree — @objectstack/service-settings gains two published exports, a widened setMany options type and a new predicate-input field; declare Clause-②: yes (narrowing) identically in the PR body and the changeset, levels and Metadata-protocol: none unchanged.
• SHOULD-FIX (④): forward only the forwarded-address headers in SettingsRequestTransport, or state in its TSDoc that predicates receive credential-bearing headers.
• SHOULD-FIX (④): the outside refusal copy should say "does not match" (or name the matcher's IPv4-CIDR / exact reach); file the IPv6-CIDR gap on the gate as a card.
• SHOULD-FIX (④, nit): registerWritePredicate? on SettingsReadSurface takes unknown, not any.
• SEAT (③): file the clear-skips family and the fix(plugin-security): every member reads and posts comments, and reads the activity history, of the records they can read #30222 dogfood red as cards; name the docs and console halves as cards.

Implemented-by: session_01Utp6Ca3N2EsTAqg7jhabeL
Reviewed-by: session_01Utp6Cbvcmv8YWFhFJwzjKL

VERDICT: FAIL

Record taken 2026-11-05T05:57Z.

domain:server#2 · os-bill · session_01Utp6Cbvcmv8YWFhFJwzjKL

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 8767d6aa81725636037589b29b3ad59a9b4a37e9
Local-runs: none
Scope: packages/plugins/plugin-auth/src/allowed-ip-ranges.ts, packages/plugins/plugin-auth/src/auth-plugin.ts, packages/services/service-settings/src/index.ts, packages/services/service-settings/src/settings-routes.ts, packages/services/service-settings/src/settings-service.ts, packages/services/service-settings/src/settings-service.types.ts, packages/services/service-settings/src/settings-write-predicate-transport.test.ts, .changeset/30203-allowed-ip-ranges-live.md + packages/plugins/plugin-auth/src/client-address.ts (resolveClientAddress, firstHeader), packages/plugins/plugin-auth/src/client-address-forwarding.ts (FORWARDED_CLIENT_ADDRESS_HEADERS), packages/plugins/plugin-auth/src/client-address-vendor.ts (the vendored reader's one header), packages/plugins/plugin-auth/src/auth-manager.ts (resolveClientAddress, ipMatchesRange, isClientIpAllowed), the D5 gate block and transportOf in auth-plugin.ts, packages/plugins/plugin-auth/src/allowed-ip-ranges.pin.test.ts (unchanged by the delta; the trustProxy case), packages/plugins/plugin-hono-server/src/adapter.ts (rawHeaders = c.req.header(), readRemoteAddress), packages/spec/src/contracts/http-server.ts (IHttpRequest.headers, remoteAddress), packages/services/service-settings/src/localization-currency-lock.ts and settings-write-predicate.test.ts (the other registerWritePredicate callers), packages/plugins/plugin-auth/src/index.ts and package.json (whether the new module is republished), PR #30298 at 249ec4c4 (for ③), cards #30320 and #30255 (for ③). Inputs: card #30203 body and comments 6648444250, 6649086146, 6650755695, 6650829184; PR #30309 body as replaced at 06:58 UTC, file list (9 files, +679 / -18 against main), the net diff origin/main...8767d6aa, the delta 89ff3aa9..8767d6aa (one commit, 8 files, +191 / -25; no main merge in the range); record 6650936040; the check-runs on this head. This record reviews the DELTA against record 6650936040; the judgments of that record on the unchanged parts stand and are not restated.

① Derived judgments

• The delta, hunk by hunk. (a) settings-service.ts: the predicate registry now stores { predicate, requestHeaders } per key, registerWritePredicate takes an optional fourth options whose requestHeaders are lower-cased into a Set at registration, and refuseByWritePredicates hands each predicate narrowTransport(display.transport, registered.requestHeaders) instead of the whole transport. narrowTransport copies only the header entries whose lower-cased name is in the set, under their incoming spelling, plus remoteAddress when present; it builds a fresh object per predicate, so no predicate can mutate what a sibling sees. (b) settings-service.types.ts: new SettingsWritePredicateOptions, and SettingsWritePredicateInput.transport's TSDoc now states the narrowing. (c) index.ts: SettingsWritePredicateOptions exported. (d) settings-routes.ts: comment only; the route still hands the full req.headers and req.remoteAddress to the service, which is right: narrowing per predicate has to happen where the registrations are known. (e) auth-plugin.ts: the structural SettingsReadSurface.registerWritePredicate? takes input: unknown and an optional options, and the registration names FORWARDED_CLIENT_ADDRESS_HEADERS. (f) allowed-ip-ranges.ts: the predicate's parameter is unknown, read structurally through AllowedIpRangesWriteInput; the outside copy in all four locales says no entry matches. (g) the new settings-write-predicate-transport.test.ts, three cases. (h) the changeset's declaration and prose. Every accept-set change of the delta is a narrowing of what a predicate receives (fewer headers), not of what an administrator can save; the save's accept set is unchanged from 89ff3aa9.
• The declaration is now true and complete. Against the net diff of @objectstack/service-settings (published, 18.3.0) the public surface gains exactly: the exported types SettingsRequestTransport, SettingsWriteOptions, SettingsWritePredicateOptions; setMany's fourth parameter typed SettingsWriteOptions in place of SettingsDisplayOptions; registerWritePredicate's optional fourth options; SettingsWritePredicateInput.transport. The Clause-②: yes (narrowing) line names each of these six and nothing that is not there. @objectstack/plugin-auth (published, 18.3.0) adds allowed-ip-ranges.ts, which neither its index.ts nor its exports map republishes, so no unnamed widening hides there. The narrowing half of the line (a console save none of whose entries matches the saving address is refused where it was stored before) is the behaviour 89ff3aa9 already carried and record 6650936040 judged right. The must-fix of that record is closed.
• Callers that predate the fourth parameter still fit. localization-currency-lock.ts declares a host interface with the three-parameter registerWritePredicate and calls it with three; settings-write-predicate.test.ts calls it with three. The parameter defaults to {}, a currency-lock predicate receives headers: {} plus the peer address on a request write, and it reads neither. Right.

② Semver level

• Changeset .changeset/30203-allowed-ip-ranges-live.md: @objectstack/plugin-auth: patch, @objectstack/service-settings: patch; Metadata-protocol: none, so patch is the level ruling A assigns; a non-protocol narrowing ships patch with its banner. The **BREAKING** banner is present and names who moves; the ADR-0087 marker is present, exactly one, disposition not-required, category no-migration-prescription, and the body still carries no FROM → TO prescription, so the category holds. Check Changeset and Lint & Repo Gates (which runs the ADR-0087 registration gate) are green on this head.
• Declaration lines: Clause-②:, Metadata-protocol: and Skills-docs: are byte-identical between the PR body (as replaced at 06:58 UTC) and the changeset (sha256 of each line compared). Clause-②: yes (narrowing) is a well-formed arm of the closed pair. Nothing to fix here.

③ Boundary flags

• Record 6650936040, item by item. MUST-FIX (declaration false): closed, ① above. SHOULD-FIX (whole header map to every predicate): closed by narrowTransport plus registration-time requestHeaders; judged in ④. SHOULD-FIX (refusal copy says "does not include"): closed in en, zh-CN, ja-JP, es-ES ("No entry in this list matches …" and its equivalents); the IPv6-CIDR gap is filed as card Allowed IP ranges: an IPv6 CIDR entry never matches at the sign-in gate or the save check (matcher reads IPv4 CIDR and exact addresses only), while the setting promises CIDR ranges #30320 (open, reads allowed_ip_ranges and ipMatchesRange, marked read-not-measured). SHOULD-FIX (input: any): closed, unknown at both the structural surface and the predicate factory. SEAT items: main red: Dogfood Regression Gate (2/3) fails permission-set-clone-door after PR #30222 (member_default grants sys_comment) #30255 is the main-red anchor card for the permission-set-clone-door dogfood red; the clear-skips family and the docs and console halves remain the seat's to file and are not this review's gate.
• Dogfood not re-run on this head. The full dogfood the narrowing arm owes was run on 89ff3aa9 (1 red, main red: Dogfood Regression Gate (2/3) fails permission-set-clone-door after PR #30222 (member_default grants sys_comment) #30255, main's). The delta changes which headers reach a predicate, refusal wording, and types; the only in-tree predicate that reads transport is the allow-list one, and its pin (the trustProxy case included) is green in Test Core on this head, as are the three new service-settings cases. Accepted as a declared deviation; it is not a reason to withhold the record.
• Composition with PR fix(plugin-auth)!: saving the auth settings refuses to turn off the last way to sign in #30298 (card Authentication settings: turning off email and password with no other sign-in method saves without warning, and everyone is locked out #30202), re-read at its head 249ec4c4 (unchanged since record 6650936040). Its diff touches no service-settings file and its body places the batch field outside its card. If a later head adds batch to SettingsWritePredicateInput, it lands next to the transport? member and the multi-line input literal in refuseByWritePredicates, which this delta edits again (the narrowTransport call); the second to land takes a rebase at those two spots, both fields optional, semantics compose. Flagged, no ruling needed.
• Open questions in the PR body: none; none found.

④ Design judgment

Judged on the tree, trying to break narrowTransport and the per-predicate header contract against the gate it must agree with.

• Header-name case — holds. Registration lower-cases every name (new Set(names.map(toLowerCase))); narrowTransport compares name.toLowerCase() of each incoming key against that set and keeps the incoming spelling. So requestHeaders: ['X-Forwarded-For', 'x-real-ip'] against lower-case incoming keys matches (pinned in the new test, first case). Both doors take their header map from Hono's c.req.header(): the gate directly (D5 block, auth-plugin.ts), the save through the hono adapter's rawHeaders = c.req.header() into IHttpRequest.headers; Hono lower-cases keys, and the list is lower-case, so every lookup lines up. The one spelling that would not match is an adapter delivering mixed-case keys: narrowTransport would still pass them through (it matches case-insensitively), but resolveClientAddress's firstHeader reads headers[name] ?? headers[name.toLowerCase()] with a lower-case name, so it would miss them at the gate and at the save alike. Same answer at both doors is what the rule requires; no finding against this delta.
• Coverage of the forwarded headers — complete by construction. resolveClientAddress reads forwarded headers only inside for (const name of FORWARDED_CLIENT_ADDRESS_HEADERS), and the plugin registers that very constant, so the predicate receives every header the address rule can read (x-forwarded-for, x-real-ip) and no other. No Forwarded, CF-Connecting-IP or True-Client-IP reader exists in plugin-auth, the runtime or the hono adapter (grepped); the vendored library reads only the platform-written x-objectstack-client-address, which the platform sets from the already-resolved address, never from the client. If a later change widens the rule's list, the registration widens with it, because it names the list and not two literals. The save and the gate therefore judge the same address under trustProxy on and off. Ablation E in the body (registering []) reds exactly the trustProxy case, which is the failure shape a missing header would produce; the pin would catch a drift.
• A predicate with no requestHeaders — receives headers: {} and the peer address (pinned, second case). This is the right default: the peer address is the one fact a client cannot forge, and a predicate that wants a header says so where its registration can be audited. The currency-lock predicate is such a one and reads neither.
• Credential headers — do not reach the allow-list predicate (pinned, first case: cookie, authorization, x-api-key present on the request, absent from the narrowed transport). Ablation F (pass every header) reds both header cases. The TSDoc on SettingsWritePredicateOptions.requestHeaders says "lower-case"; the matching is case-insensitive, so the doc under-promises harmlessly. No action.
• In-process writes — unchanged: display.transport absent ⇒ no transport key on the input at all (pinned, third case); narrowTransport is never reached.
• input: unknown — the predicate reads (input ?? {}) as AllowedIpRangesWriteInput and then guards transport, next (through parseAllowedIpRanges's typeof check) and manager(); a malformed input yields undefined, never a throw. The structural pick keeps plugin-auth free of a service-settings type import, as the prior record asked.
• Refusal copy — "No entry in this list matches …" is true for the IPv6-CIDR case the prior record described (an entry textually containing the address that the matcher cannot read) and for the plain case; the recovery sentence is unchanged. Should-fix (nit, non-blocking): the changeset's **BREAKING** banner and the PR title still say the list "does not include" / "leaves out" the saving address; the upgrading administrator reads the banner in CHANGELOG.md with the same IPv6 imprecision the copy fix removed. One phrase: "that no entry of which matches the address they are connected from".
• Tests: the new file boots the real SettingsService with the shipped branding manifest and the real settings routes, and asserts the narrowed transport with toEqual (an exact shape, so an extra header would fail it). Good.

Check-runs on 8767d6aa (polled at 07:00 and 07:02 UTC): 52 runs, 37 success, 15 skipped (the path-filtered UI lanes and opt-in harnesses), 0 in_progress, 0 failure. Green: Lint & Repo Gates and every Lint · lane, TypeScript Type Check and its four lanes, Test Core and all eight shards, Build Core, Governed Surface Queue Guard, Check Changeset, Check PR Size, Dogfood Regression Gate, Test UI, Live E2E UI, the PR-body guards. No red on this head.

Findings

• Record 6650936040: MUST-FIX closed; SHOULD-FIX ① (header narrowing) closed; SHOULD-FIX ② (refusal copy; IPv6-CIDR card Allowed IP ranges: an IPv6 CIDR entry never matches at the sign-in gate or the save check (matcher reads IPv4 CIDR and exact addresses only), while the setting promises CIDR ranges #30320) closed; SHOULD-FIX ③ (unknown) closed.
• SHOULD-FIX (④, nit, non-blocking): align the changeset **BREAKING** banner and the PR title with the refusal copy ("no entry of which matches" rather than "does not include" / "leaves out").
• FLAG (③): fix(plugin-auth)!: saving the auth settings refuses to turn off the last way to sign in #30298 batch field, compose risk only; the second to land rebases the SettingsWritePredicateInput member and the refuseByWritePredicates input literal.
• SEAT (③): the clear-skips family card and the docs and console halves remain to be filed.

Implemented-by: session_01Utp6Ca3N2EsTAqg7jhabeL
Reviewed-by: session_01Utp6Cbvcmv8YWFhFJwzjKL

VERDICT: PASS

Record taken 2026-11-05T07:05Z.

domain:server#2 · os-bill · session_01Utp6Cbvcmv8YWFhFJwzjKL

维护者速读

• 改了什么： 两件。① 清空「允许的 IP 段」后立即生效，运行中的名单退回部署自己声明的名单，不用再重启。② 在设置页保存一份不匹配保存者自己地址的名单时，直接拒绝（400 SETTINGS_VALIDATION），提示里写明对方的地址，以及已经锁在门外时的补救办法：把 OS_AUTH_ALLOWED_IP_RANGES 设成空。为此 service-settings 多了一条通道，把请求里的地址交给写入谓词：每个谓词只拿到自己登记要的头，cookie、authorization、API key 都到不了。
• 为什么改： 原来管理员能把自己排除在外而毫无提示，清空字段也要重启才生效（Allowed IP ranges: an administrator can exclude their own address unwarned, and clearing the field does not take effect until a restart #30203）。
• 风险与回滚： 只收窄一种保存：设置页上会排除保存者自己的名单（BREAKING，changeset 写明，带 ADR-0087 标记）。启动、种子数据、代码里的写入不受影响。回滚即撤本 PR。
• 先看： packages/plugins/plugin-auth/src/allowed-ip-ranges.ts，再看 settings-service.ts 的 narrowTransport。
• 两分钟验证： pnpm --filter @objectstack/plugin-auth exec vitest run src/allowed-ip-ranges.pin.test.ts。
• 需要您做的： 无，席位经合并队列落地（非受管面，697 行）。
• 席位意见： ACCEPT。契约复审第一轮 FAIL（6650936040，申报错），已改；增量复审 PASS（6651963356）。

席位核对 — ACCEPT · domain:server#2 · head 8767d6aa81725636037589b29b3ad59a9b4a37e9

• 形态: draft, author objectstack-fleet[bot] (relay pr_create), no assignee, no review request; 9 files, +679 −18; check-governed-merges --pr 30309: NOT governed (0 of 9 paths), 697 lines ≤ 3000; mergeable clean.
• 契约复审: CONTRACT_REVIEW_TIER, narrowing face. FAIL 6650936040 on 89ff3aa9 (must-fix: Clause-②: no (narrowing) false, the published @objectstack/service-settings surface widened). Delta PASS 6651963356 on 8767d6aa (one commit, no main merge): must-fix closed; header narrowing per predicate (requestHeaders at registration, case-insensitive, fresh object per predicate), FORWARDED_CLIENT_ADDRESS_HEADERS equals the list resolveClientAddress reads, so save and gate judge the same address; copy says no entry matches; input: unknown.
• Declarations (seat read): Clause-②: yes (narrowing), Metadata-protocol: none, Skills-docs: byte-identical in the PR body (relay-written from server-seat2/pr-30203-body.md, read back identical) and the changeset; patch for @objectstack/plugin-auth and @objectstack/service-settings; BREAKING banner, one ADR-0087 marker. Supersedes the seat's claim correction 6650829184 (which recorded no (narrowing) pending this review).
• Dev readings (8767d6a): plugin-auth 3885 passed, service-settings 1162 passed, both typecheck 0; ablations E (requestHeaders empty → trustProxy case red) and F (all headers handed → 2 red) restored; derived gates 64/65 exit 0, dual-build NOT MEASURED (needs a whole-workspace build; CI ran it); pnpm lint 0. Full dogfood ran on 89ff3aa9; its one red was main red: Dogfood Regression Gate (2/3) fails permission-set-clone-door after PR #30222 (member_default grants sys_comment) #30255 (main's, now reverted and fixed forward in PR fix(runtime, metadata-protocol): the permission-set clone door copies a set that grants on an object this deployment does not install, and member_default's feed grants re-land #30310). Accepted: the delta changes only predicate header narrowing and copy, covered by the pin and the new test.
• 门禁 check-runs: 52 runs, 37 success, 15 skipped, 0 failed.
• Accepted nit (not fixed): the changeset BREAKING banner and PR title still say "leaves out" where the refusal copy now says no entry matches; same meaning for IPv4, and the IPv6-CIDR gap is Allowed IP ranges: an IPv6 CIDR entry never matches at the sign-in gate or the save check (matcher reads IPv4 CIDR and exact addresses only), while the setting promises CIDR ranges #30320.
• 范围外去向: Authentication settings: clearing a key (or resetting the namespace) answers saved, but the running value keeps the last stored one until a restart (lockout threshold, max sessions per user and siblings) #30312 (clearing other auth keys needs a restart, every isExplicit branch), Allowed IP ranges console field: show the caller's current address before saving, and show the refusal's address when a save would lock the admin out #30313 (console shows the caller's address), Docs: authentication page should state that an allowed IP ranges save excluding your own address is refused, and how to recover with OS_AUTH_ALLOWED_IP_RANGES #30314 (docs: the refusal and the OS_AUTH_ALLOWED_IP_RANGES recovery), Allowed IP ranges: an IPv6 CIDR entry never matches at the sign-in gate or the save check (matcher reads IPv4 CIDR and exact addresses only), while the setting promises CIDR ranges #30320 (IPv6 CIDR never matches).
• 落地条款: Fixes Allowed IP ranges: an administrator can exclude their own address unwarned, and clearing the field does not take effect until a restart #30203. Ordinary queue landing by this seat: pr_ready + automerge_enable on this head. PR fix(plugin-auth)!: an organization cannot require MFA while two-factor enrollment is off (#30201) #30293 (in the queue) and PR fix(plugin-auth)!: saving the auth settings refuses to turn off the last way to sign in #30298 edit the same auth-plugin.ts; the queue rebuilds on each merge, and PR fix(plugin-auth)!: saving the auth settings refuses to turn off the last way to sign in #30298 will add a batch field next to transport in the service-settings predicate input (merge main first).